RESTful API

What is a REST API?#

The clients' programs use web APIs to communicate with the web servers. A web API takes the client's requests, interacts with the back-end servers, and responds back to the clients.

Many of today's APIs can be classified as REST APIs. Our purpose is not mere understanding but rather drawing insights into the REST architectural style of developing APIs.

Note: A REST API is a web API that conforms to the commonly used REST architectural style.

Many programming languages and protocols use CRUD operations for manipulating data. For example, in the SQL database, we use insert, select, update, and delete. Similarly, interacting with the REST application often involves CRUD operations because the REST-based applications are built around resources that need to be created, read, updated, and deleted. REST APIs are protocol agnostics; however, the underlying protocol they use widely for communication is HTTP. Therefore, the CRUD operations can be easily mapped to major HTTP methods, as shown in the following table.

What makes an API RESTful?#

In the previous lesson, we studied the REST constraints, collectively called a web architectural style. Now, let's revisit those constraints from a different perspective. This time, we’ll see how an API should follow those constraints that make them a REST API.

REST API best practices#

Now that we understand what makes an API RESTful, let's discuss some best practices when developing RESTful APIs.

• Exchange of data via JSON: The REST APIs should use JSON format for sending and receiving data. The other formats—like XML and YAML— lack some common procedures for encoding and decoding the data. On the other hand, a wide range of server-side technologies offer built-in methods to parse and manipulate JSON data. For example, JSON.parse() and JSON.stringify() are used to convert a JSON string to a JSON object and convert a JSON object to JSON string, respectively.

Note: Whenever the data is sent in JSON format to the client, the server should set Content-Type in the HTTP header to application/json . This way, the clients look at the Content-Type header and correctly interpret JSON data.

• Nesting on endpoints: Different endpoints containing the associated information should be interlinked to make them easier to understand. For example, imagine a platform where multiple users can post their articles. A nesting like https://www.example.com/posts/user seems logical. Similarly, if we need to get comments for a post, we should add /postId/comments at the end of the /posts path. The resultant endpoint will become https://www.example.com/posts/postId/comments. This is a good practice through which we can avoid mirroring database structure in our endpoints, keeping the data safe from attackers.

• Use nouns instead of verbs in the paths: We should strictly avoid using verbs instead of nouns in the endpoints. The verbs represent methods (the HTTP already has such methods), while the noun represents entities. Using verbs in the endpoints is not useful and makes the endpoints unnecessarily long. For example, instead of the https://www.example.com/posts/getUser endpoint, which has the verb get, we should use https://www.example.com/posts/user.

• Error management and standard error codes: We should use HTTP status codes regularly when an error occurs to indicate the nature of the error. This helps the API consumers to understand the problem and handle it on their end if needed. Moreover, we should also add an error message with the status code to help users to take some corrective measures.

• Filtering and pagination: Sometimes, the database gets incredibly large. Fetching data from such a database becomes time-consuming and reduces performance. Filtering reduces the requested information from the server and thus the end-to-end query latency. For example, the https://www.example.com/posts?author=fahim endpoint will fetch the posts authored by fahim instead of listing all the posts. Similarly, there is a need to paginate data to fetch partial results at a time to minimize page loading time and reduce the burden on the client for loading a bulk of data all at once. Filtering and pagination reduce the usage of server resources and increase performance.

• Adopting standard security practices: Another best practice we should adopt is making our API invulnerable to malicious attacks. In addition, the communication between the client and server should also be private. More importantly, we should also ensure that the server doesn't send unrelated information to unrelated users. This way, we can restrict users to the data intended for them rather than allow them to access other users' data. For this purpose, we can use HTTPS running on top of SSL/TLS. For example, https://www.example.com/ runs on TLS, while the http://www.example.com/ doesn't use any TLS features.

• API versioning: We should offer different versions of the API if we make any changes to it that might affect customers. Versioning can be done in line with semantic versions, like the majority of contemporary software—for example, 2.1.6, to denote major version 2, minor version 1, and the sixth patch. This allows us to gradually discontinue old endpoints rather than forcing everyone to migrate to the new API simultaneously. The v1 endpoint may still be useful for individuals who don't want to migrate, while the v2, with its eye-catching additional features, can benefit those who are ready to switch. API versioning can be done by adding /v1 or /v2 to the API path—for example, https://www.example.com/v1 and https://www.example.com/v2.

• API documentation: Another good practice is to have comprehensive API documentation to help developers and other consumers to understand the API and use it in their applications. A good API document consists of the following:

  • Detailed and clear explanation of API endpoints and all other functionality with a proper use case

  • SDK implementation provided in several state-of-the-art programming languages

  • Clear instructions related to the integration

  • Clear updates on the API lifecycle

  • Error messages and proper status codes to convey clear information about the error

Advantages of REST APIs#

REST architecture influences how we view, edit, and transfer material online. It’s the preferred choice of many well-known web services. Let's look at the reasons behind this choice in the list below:

• Adaptability: The REST APIs are adaptable because they are able to transfer data in a wide variety of formats and handle a wide variety of requests.

• Scalability: Regardless of size or capabilities, they are made to communicate with any two pieces of software. A web application's REST API will be able to swiftly handle the growing volume and variety of queries as it expands and adds more services.

• Compatibility: REST APIs employ existing web technologies, so they are very simple to create and operate. A REST API just requires the resource's URL to request it.

Summary#

In this lesson, we discussed the features that make a REST API . The REST APIs are protocol agnostics, but since they should use an underlying protocol for their operability, HTTP is a widespread protocol adopted by REST APIs. One of the reasons for the adoption of HTTP for REST API is that this protocol, by default, fulfills many REST architectural constraints—the significant ones are client-server, cacheability, statelessness, and uniform interface. Further, we also discussed some best practices for designing a REST API and the advantages that REST API brings.